home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / ClassLoader.java < prev    next >
Text File  |  1998-09-22  |  16KB  |  409 lines
  1. /*
  2.  * @(#)ClassLoader.java    1.58 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.lang;
  16.  
  17. import java.io.InputStream;
  18. import java.util.Hashtable;
  19.  
  20. /**
  21.  * The class <code>ClassLoader</code> is an abstract class. 
  22.  * Applications implement subclasses of <code>ClassLoader</code> in 
  23.  * order to extend the manner in which the Java Virtual Machine 
  24.  * dynamically loads classes. 
  25.  * <p>
  26.  * Normally, the Java Virtual Machine loads classes from the local 
  27.  * file system in a platform-dependent manner. For example, on UNIX 
  28.  * systems, the Virtual Machine loads classes from the directory 
  29.  * defined by the <code>CLASSPATH</code> environment variable. 
  30.  * <p>
  31.  * However, some classes may not originate from a file; they may 
  32.  * originate from other sources, such as the network, or they could 
  33.  * be constructed by an application. The method 
  34.  * <code>defineClass</code> converts an array of bytes into an 
  35.  * instance of class <code>Class</code>. Instances of this newly 
  36.  * defined class can be created using the <code>newInstance</code> 
  37.  * method in class <code>Class</code>. 
  38.  * <p>
  39.  * The methods and constructors of objects created by a class loader 
  40.  * may reference other classes. To determine the class(es) referred 
  41.  * to, the Java Virtual Machine calls the <code>loadClass</code> 
  42.  * method of the class loader that originally created the class. If 
  43.  * the Java Virtual Machine only needs to determine if the class 
  44.  * exists and if it does exist to know its superclass, the 
  45.  * <code>resolve</code> flag is set to <code>false</code>. However, 
  46.  * if an instance of the class is being created or any of its methods 
  47.  * are being called, the class must also be resolved. In this case 
  48.  * the <code>resolve</code> flag is set to <code>true</code>, and the 
  49.  * <code>resolveClass</code> method should be called. 
  50.  * <p>
  51.  * For example, an application could create a network class loader 
  52.  * to download class files from a server. Sample code might look like:
  53.  * <ul><code>
  54.  *   ClassLoader loader = new NetworkClassLoader(host, port);<br>
  55.  *   Object main = loader.loadClass("Main", true).newInstance();<br>
  56.  *      . . .
  57.  * </code></ul>
  58.  * <p>
  59.  * The network class loader subclass must define the method 
  60.  * <code>loadClass</code> to load a class from the network. Once it 
  61.  * has downloaded the bytes that make up the class, it should use the 
  62.  * method <code>defineClass</code> to create a class instance. A 
  63.  * sample implementation is: 
  64.  * <p><hr><blockquote><pre>
  65.  *     class NetworkClassLoader {
  66.  *         String host;
  67.  *         int port;
  68.  *         Hashtable cache = new Hashtable();
  69.  *         private byte loadClassData(String name)[] {
  70.  *         // load the class data from the connection
  71.  *          . . .
  72.  *         }
  73.  * 
  74.  *         public synchronized Class loadClass(String name,
  75.  *                                             boolean resolve) {
  76.  *             Class c = cache.get(name);
  77.  *             if (c == null) {
  78.  *                 byte data[] = loadClassData(name);
  79.  *                 c = defineClass(data, 0, data.length);
  80.  *                 cache.put(name, c);
  81.  *             }
  82.  *             if (resolve)
  83.  *                 resolveClass(c);
  84.  *             return c;
  85.  *         }
  86.  *     }
  87.  * </pre></blockquote><hr>
  88.  *
  89.  * @author  Arthur van Hoff
  90.  * @version 1.58, 07/01/98
  91.  * @see     java.lang.Class
  92.  * @see     java.lang.Class#newInstance()
  93.  * @see     java.lang.ClassLoader#defineClass(byte[], int, int)
  94.  * @see     java.lang.ClassLoader#loadClass(java.lang.String, boolean)
  95.  * @see     java.lang.ClassLoader#resolveClass(java.lang.Class)
  96.  * @since   JDK1.0
  97.  */
  98. public abstract class ClassLoader {
  99.     /**
  100.      * If initialization succeed this is set to true and security checks will
  101.      * succeed. Otherwise the object is not initialized and the object is
  102.      * useless.
  103.      */
  104.     private boolean initialized = false;
  105.  
  106.     /**
  107.      * This is a mapping of all String => Class done by this classloader.
  108.      * Each Class in the table will either have a null class loader, or 
  109.      * "this" as its classloader
  110.      */
  111.     private Hashtable classes = new Hashtable();
  112.  
  113.     /**
  114.      * Constructs a new class loader and initializes it. 
  115.      * <p>
  116.      * If there is a security manager, its 
  117.      * <code>checkCreateClassLoader</code> method is called. This may 
  118.      * result in a security exception. 
  119.      *
  120.      * @exception  SecurityException  if the current thread does not have
  121.      *               permission to create a new class loader.
  122.      * @see       java.lang.SecurityException
  123.      * @see       java.lang.SecurityManager#checkCreateClassLoader()
  124.      * @since     JDK1.0
  125.      */
  126.     protected ClassLoader() {
  127.     SecurityManager security = System.getSecurityManager();
  128.     if (security != null) {
  129.         security.checkCreateClassLoader();
  130.     }
  131.     init();
  132.     initialized = true;
  133.     }
  134.  
  135.     /**
  136.      * Requests the class loader to load and resolve a class with the specified 
  137.      * name. The <code>loadClass</code> method is called by the Java 
  138.      * Virtual Machine when a class loaded by a class loader first 
  139.      * references another class. Every subclass of class 
  140.      * <code>ClassLoader</code> must define this method. 
  141.      * <p>
  142.      * Class loaders should use a hashtable or other cache to avoid 
  143.      * defining classes with the same name multiple times. 
  144.      *
  145.      * @param      name      the name of the desired <code>Class</code>.
  146.      * @return     the resulting <code>Class</code>, or <code>null</code>
  147.      *             if it was not found.
  148.      * @exception  ClassNotFoundException  if the class loader cannot find
  149.      *               a definition for the class.
  150.      * @since      JDK1.1
  151.      */
  152.     public Class loadClass(String name) throws ClassNotFoundException
  153.     {
  154.     return loadClass(name, true);
  155.     }
  156.  
  157.     /**
  158.      * Resolves the specified name to a Class. The method loadClass() is 
  159.      * called by the virtual machine.
  160.      * <p>
  161.      * If the <code>resolve</code> flag is true, the method should call 
  162.      * the <code>resolveClass</code> method on the resulting class object.
  163.      * <p>
  164.      * As an abstract method, loadClass() must be defined in a subclass of 
  165.      * ClassLoader. By using a Hashtable, you can avoid loading the same 
  166.      * Class more than once.
  167.      * 
  168.      * @param       name     the name of the desired Class.
  169.      * @param      resolve  true if the Class needs to be resolved.
  170.      * @return       the resulting Class, or null if it was not found.
  171.      * @exception  ClassNotFoundException  if the class loader cannot find
  172.      *               a definition for the class.
  173.      * @see       java.util.Hashtable
  174.      * @since      JDK1.0
  175.      */
  176.     protected abstract Class loadClass(String name, boolean resolve)
  177.     throws ClassNotFoundException;
  178.  
  179.     /**
  180.      * Converts an array of bytes into an instance of class 
  181.      * <code>Class</code>. 
  182.      * Before the Class can be used it must be resolved.  This
  183.      * method is deprecated in favor of the version that takes a
  184.      * "name" as a first argument, and is more secure.
  185.      *
  186.      * @param      data     the bytes that make up the <code>Class</code>.
  187.      * @param      offset   the start offset of the <code>Class</code> data.
  188.      * @param      length   the length of the <code>Class</code> data.
  189.      * @return     the <code>Class</code> object that was created from the data.
  190.      * @exception  ClassFormatError  if the data does not contain a valid Class.
  191.      * @see        ClassLoader#loadClass(java.lang.String, boolean)
  192.      * @see        ClassLoader#resolveClass(java.lang.Class)
  193.      * @since      JDK1.0
  194.      * @deprecated Replaced by defineClass(java.lang.String, byte[], int, int).
  195.      */
  196.     protected final Class defineClass(byte data[], int offset, int length) { 
  197.     return defineClass(null, data, offset, length);
  198.     }
  199.  
  200.     /**
  201.      * Converts an array of bytes to an instance of class
  202.      * Class. Before the Class can be used it must be resolved.
  203.      *
  204.      * @param       name     the expected name of the class; null if unknown;
  205.      *                      using '.' and not '/' as separator, and without
  206.      *                      a trailing ".class" suffix.
  207.      * @param      data     the bytes that make up the <code>Class</code>.
  208.      * @param      offset   the start offset of the <code>Class</code> data.
  209.      * @param      length   the length of the <code>Class</code> data.
  210.      * @return     the <code>Class</code> object that was created from the data.
  211.      * @exception  ClassFormatError  if the data does not contain a valid Class.
  212.      * @see        ClassLoader#loadClass(java.lang.String, boolean)
  213.      * @see        ClassLoader#resolveClass(java.lang.Class)
  214.      * @since      JDK1.1
  215.      */
  216.     protected final Class defineClass(String name,
  217.                       byte data[], int offset, int length) { 
  218.     check();
  219.     Class result = defineClass0(name, data, offset, length);
  220.     if (result != null) 
  221.         classes.put(result.getName(), result);
  222.     return result;
  223.     }
  224.  
  225.     /**
  226.      * Resolves the class so that an instance of the class can be 
  227.      * created, or so that one of its methods can be called. This method 
  228.      * should be called by <code>loadClass</code> if the resolve flag is 
  229.      * <code>true</code>. 
  230.      *
  231.      * @param   c   the <code>Class</code> instance to be resolved.
  232.      * @see     java.lang.ClassLoader#defineClass(java.lang.String, byte[], int, int)
  233.      * @since   JDK1.0
  234.      */
  235.     protected final void resolveClass(Class c) { 
  236.     check();
  237.     resolveClass0(c);
  238.     }
  239.  
  240.     /**
  241.      * Finds the system class with the specified name, loading it in if 
  242.      * necessary. 
  243.      * <p>
  244.      * A system class is a class loaded from the local file system in a 
  245.      * platform- dependent way. It has no class loader. 
  246.      *
  247.      * @param      name   the name of the system <code>class</code>.
  248.      * @return     a system class with the given name.
  249.      * @exception  ClassNotFoundException  if it could not find a definition
  250.      *               for the class.
  251.      * @exception  NoClassDefFoundError    if the class is not found.
  252.      * @since      JDK1.0
  253.      */
  254.     protected final Class findSystemClass(String name) 
  255.     throws ClassNotFoundException {
  256.     check();
  257.     return findSystemClass0(name);
  258.     }
  259.  
  260.     /**
  261.      * Sets the signers of a class. This is called after defining a class,
  262.      * by signature-aware class loading code.
  263.      *
  264.      * @since   JDK1.1
  265.      */
  266.     protected final void setSigners(Class cl, Object[] signers) {
  267.         check();
  268.     // make a check which will take cl.getClassLoader and
  269.     // check if it is != this.
  270.     cl.setSigners(signers);
  271.     }
  272.  
  273.     /**
  274.      * Initializes the Class loader.
  275.      */
  276.     private native void init();
  277.     private native Class defineClass0(String name, 
  278.                       byte data[], int offset, int length);
  279.     private native void resolveClass0(Class c);
  280.     private native Class findSystemClass0(String name) 
  281.         throws ClassNotFoundException;
  282.  
  283.     private void check() { 
  284.     if (initialized == true) 
  285.         return;
  286.     throw new SecurityException("ClassLoader object not initialized.");
  287.     }
  288.  
  289.     /**
  290.      * @since   JDK1.1
  291.      */
  292.     final protected Class findLoadedClass(String name) { 
  293.     return (Class)classes.get(name);
  294.     }
  295.  
  296.     /**
  297.      * Load and resolve a class.
  298.      */
  299.     final Class loadClassInternal(String name, boolean resolve) 
  300.                     throws ClassNotFoundException {
  301.     name = name.replace('/', '.');
  302.     Class cl = (Class)classes.get(name);
  303.     if (cl == null) {
  304.         cl = loadClass(name, false);
  305.         if (cl == null) 
  306.         throw new ClassNotFoundException(name);
  307.         String realName = cl.getName();
  308.         if (!realName.equals(name)) { 
  309.         throw new ClassNotFoundException(name);
  310.         }
  311.         classes.put(realName, cl);
  312.     }
  313.     if (resolve) 
  314.         resolveClass(cl);
  315.     return cl;
  316.     }
  317.  
  318.     /**
  319.      * A resource is some data (images, audio, text, etc) that wants to be
  320.      * accessed by some class code in a way that is independent of the
  321.      * location of the code.  Resources are found with cooperation of the
  322.      * class loaders, since they are the only ones who know where the class
  323.      * actually came from. <p>
  324.      *
  325.      * System resources are those that are handled by the host implemenation
  326.      * directly.  For example, they may be located in the CLASSPATH.<p>
  327.      *
  328.      * The name of a resource is a "/"-separated sequence of identifiers.
  329.      * The class Class provides convenience methods for accessing resources;
  330.      * the methods implement a convention where the package name is prefixed
  331.      * to the short name of the resource.<p>
  332.      * 
  333.      * Resources can be accessed as an InputStream, or as a URL.
  334.      *
  335.      * @see    Class
  336.      */
  337.  
  338.     /**
  339.      * Get an InputStream on a given resource..  Will return null if no
  340.      * resource with this name is found. <p>
  341.      *
  342.      * The resource name may be any system resource (e.g. follows CLASSPATH
  343.      * order).
  344.      *
  345.      * @param    name    the name of the resource, to be used as is.
  346.      * @return    an InputStream on the resource, or null if not found.
  347.      * @since   JDK1.1
  348.      */
  349.     public static final InputStream getSystemResourceAsStream(String name) {
  350.     // REMIND - This is equivalent to getSystemResource() call plus a openStream()
  351.     return getSystemResourceAsStream0(name);
  352.     }
  353.  
  354.     /**
  355.      * Find a resource with a given name.  The return is a URL to the resource
  356.      * Doing a getContent() on the URL may return an Image, an AudioClip, or
  357.      * an InputStream.<p>
  358.      *
  359.      * The resource name may be any system resource (e.g. follows CLASSPATH
  360.      * order).
  361.      *
  362.      * @param    name    the name of the resource, to be used as is.
  363.      * @return    the URL on the resource, or null if not found.
  364.      * @since   JDK1.1
  365.      */
  366.     public static final java.net.URL getSystemResource(String name) {
  367.     String s = getSystemResourceAsName0(name);
  368.     java.net.URL back;
  369.     try {
  370.         back = new java.net.URL(s);
  371.     } catch (Exception ex) {
  372.         back = null;
  373.     }
  374.     return back;
  375.     }
  376.  
  377.     /**
  378.      * Get an InputStream on a given resource.  Will return null if no
  379.      * resource with this name is found. <p>
  380.      *
  381.      * The class loader can choose what to do to locate the resource.
  382.      *
  383.      * @param    name    the name of the resource, to be used as is.
  384.      * @return    an InputStream on the resource, or null if not found.
  385.      * @since   JDK1.1
  386.      */
  387.     public InputStream getResourceAsStream(String name) {
  388.     return null;
  389.     }
  390.  
  391.     /**
  392.      * Find a resource with a given name.  The return is a URL to the resource.
  393.      * Doing a getContent() on the URL may return an Image, an AudioClip,
  394.      * or an InputStream.<p>
  395.      *
  396.      * The class loader can choose what to do to locate the resource.
  397.      *
  398.      * @param    name    the name of the resource, to be used as is.
  399.      * @return    an InputStream on the resource, or null if not found.
  400.      * @since   JDK1.1
  401.      */
  402.     public java.net.URL getResource(String name) {
  403.     return null;
  404.     }
  405.  
  406.     private static native InputStream getSystemResourceAsStream0(String name);
  407.     private static native String getSystemResourceAsName0(String name);
  408. }
  409.